<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Database Environment Management Example</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB Java Edition" />
    <link rel="up" href="env.html" title="Chapter 2. Database Environments" />
    <link rel="prev" href="envStats.html" title="Environment Statistics" />
    <link rel="next" href="dpl.html" title="Part I. Programming with the Direct Persistence Layer" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Database Environment Management Example</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="envStats.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. Database Environments</th>
          <td width="20%" align="right"> <a accesskey="n" href="dpl.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="dbenvUsageExample"></a>Database Environment Management Example</h2>
          </div>
        </div>
      </div>
      <p>
            This example provides a complete class that can open and close an environment. It is
            both extended and used in subsequent examples in this book to open and close both
            environments and databases. We do this so as to make the example code
            shorter and easier to manage. You can find this class in:
    </p>
      <pre class="programlisting"><span class="emphasis"><em>JE_HOME</em></span>/examples/je/gettingStarted/MyDbEnv.java</pre>
      <p>
        where <code class="literal"><span class="emphasis"><em>JE_HOME</em></span></code> is the location where you
        placed your JE distribution.
    </p>
      <div class="example">
        <a id="mydbenv"></a>
        <p class="title">
          <b>Example 2.1 Database Environment Management Class</b>
        </p>
        <div class="example-contents">
          <p>First we write the normal class declarations. We also set up some
      private data members that are used to manage environment creation. We
      use the class constructor to instantiate the <code class="classname">EnvironmentConfig</code>
      object that is used to configure our environment when we open it.</p>
          <a id="je_env6"></a>
          <pre class="programlisting">// File MyDbEnv.java
package je.gettingStarted;

import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Environment;
import com.sleepycat.je.EnvironmentConfig;

import java.io.File;


public class MyDbEnv {

    private Environment myEnv;

    public MyDbEnv() {} </pre>
          <p>Next we need a method to open the environment. This is responsible
      for instantiating our <code class="classname">Environment</code> object.
      Remember that instantiation is what opens the environment (or creates it
      if the creation property is set to <code class="literal">true</code> and the
      environment does not currently exist).
      </p>
          <a id="je_env7"></a>
          <pre class="programlisting">    public void setup(File envHome, boolean readOnly) 
            throws DatabaseException {

        // Instantiate an environment configuration object
        EnvironmentConfig myEnvConfig = new EnvironmentConfig();
        // Configure the environment for the read-only state as identified
        // by the readOnly parameter on this method call.
        myEnvConfig.setReadOnly(readOnly);
        // If the environment is opened for write, then we want to be 
        // able to create the environment if it does not exist.
        myEnvConfig.setAllowCreate(!readOnly);

        // Instantiate the Environment. This opens it and also possibly
        // creates it.
        myEnv = new Environment(envHome, myEnvConfig);
    } </pre>
          <p>
      Next we provide a getter method that allows us to retrieve the
      <code class="classname">Environment</code> directly. This is needed for later 
      examples in this guide.
      </p>
          <a id="je_env8"></a>
          <pre class="programlisting">    // Getter methods
    public Environment getEnv() {
        return myEnv;
    } </pre>
          <p>Finally, we need a method to close our <code class="classname">Environment</code>.
      We wrap this operation in a <code class="literal">try</code> block so that it can
      be used gracefully in a <code class="literal">finally</code> statement.</p>
          <a id="je_env9"></a>
          <pre class="programlisting">    // Close the environment
    public void close() {
        if (myEnv != null) {
            try {
                myEnv.close();
            } catch(DatabaseException dbe) {
                System.err.println("Error closing environment" + 
                     dbe.toString());
            }
        }
    }
} </pre>
          <p>
              This completes the <code class="classname">MyDbEnv</code> class. While not particularly useful
              as it currently exists, we will build upon it throughout this book so that it will
              eventually open and close all of the entity stores or databases required by our
              applications.
      </p>
          <p>
              We can now use <code class="classname">MyDbEnv</code> to open and close a database environment
              from the appropriate place in our application. For example:
      </p>
          <a id="je_env10"></a>
          <pre class="programlisting">package je.gettingStarted;

import com.sleepycat.je.DatabaseEntry;
import com.sleepycat.je.DatabaseException;

import java.io.File;

...

MyDbEnv exampleDbEnv = new MyDbEnv();

try {    
    exampleDbEnv.setup(new File("/directory/currently/exists"), true);
    ...

} catch(DatabaseException dbe) {
    // Error code goes here
} finally {
    exampleDbEnv.close();
} </pre>
        </div>
      </div>
      <br class="example-break" />
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="envStats.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="env.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="dpl.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Environment Statistics </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Part I. Programming with the Direct Persistence Layer</td>
        </tr>
      </table>
    </div>
  </body>
</html>
